home *** CD-ROM | disk | FTP | other *** search
Text File | 1996-04-05 | 5.6 KB | 136 lines | [TEXT/MWPR] |
- Introducing Sherlock
-
-
-
- Sherlock is a tracing and profiling tool for the C programming language. Sherlock macros create
- named instructions that you can enable or disable by name at any time.
-
-
- For instance, the TRACE macro takes two arguments. The first argument is a tracepoint name
- associated with the macro. The second argument is a list of one or more C statements, called the
- tracepoint actions. Here is an example of a call to the TRACE macro:
-
-
- TRACE("abc", printf("i = %d\n", i));
-
-
- The tracepoint name is "abc". The tracepoint action for this macro is the statement:
-
-
- printf("i = %d\n", i);
-
-
- This tracepoint action is executed when control reaches the macro, but only if the tracepoint named
- abc has been enabled. To find out whether tracing for abc has been enabled, the TRACE macro
- calls Sherlock’s support routines. These routines maintain a database of information and statistics
- about tracepoints.
-
-
- Typically, you enable Sherlock macros from the command line. To enable the statement above,
- add ++abc to the command line. To disable the statement, add --abc to the command line. You
- can use the wildcard characters * and ? to disable groups of Sherlock macros. For example, the
- command line arguments ++* --abc* enables all tracing except for tracepoints whose names start
- with abc. The Macintosh version of Sherlock contains routines that create a file containing a
- simulated command line.
-
-
- As stated above, tracepoint actions can contain any C statements (except initializers with braces).
- Usually tracepoint actions will print the contents of variables or data structures. The Macintosh
- version of Sherlock creates a log window, to which Sherlock sends its output by default. Output
- to the Sherlock window may also be copied to the log file. A Sherlock argument of the form
-
- ++>>file_name causes Sherlock to open the log file with the given name. Any previous log file is
- closed: only one log file can be opened at at time.
-
-
-
- The exxx family of functions simulate stream output routines found in C++. By default, these
- functions send their output to the log window. On the Macintosh, the tracepoint actions inside
- Sherlock macros should use the exxx routines. Using exxx routines the example above would be:
-
-
- TRACE("abc", es("i = "); eint(i); enl());
-
-
- The es routine prints a string, the eint routine prints an integer, and the enl routine prints a newline.
- Many other exxx routines exist: they provide a type-safe replacement for fprintf. Most of these
- functions are defined in the file LIBes.c, but the function es() itself must be defined in each
- application. See the file SDIF_es.c for a typical definition.
-
-
- Sherlock gathers statistics about tracing instructions. Sherlock counts how many times each
- macro was encountered and the time spent between special macros called entry macros and exit
- macros. You can to print these statistics at any time, either from Sherlock menu or by inserting the
- SL_DUMP macro into your program.
-
-
- You can insert or delete Sherlock macros automatically, using the SPP and SDEL tools. The SPP
- application inserts Sherlock macros into your source code and the SDEL application deletes them.
- However, Sherlock macros need never be removed from your program—undefining the
- SHERLOCK compile-time variable causes all Sherlock macros to expand to do-nothing code.
-
-
- Macintosh support routines
-
- The Macintosh version of Sherlock provides two additional support routines, w_mac_init and
- w_applEvent, that simplify porting existing applications to the Macintosh. These routines are
- described fully in the Chapter called “Installing Sherlock.”
-
-
- w_mac_init optionally inserts various menus into the menu bar. One of these menus is the
- Sherlock menu. The Sherlock menu allows you to control tracing and statistics while your
- application is running. The w_mac_init function can also insert standard Apple, File and Edit
- menus into your application.
-
-
- w_applEvent provides a minimal event loop. w_applEvent need not be used in applications that
- have their own event loop and handle their own menus.
-
- The Sherlock Menu
-
- The w_mac_init function inserts the Sherlock Menu into your application’s menu bar. The
- Sherlock Menu contains the following items:
-
-
- Menu item Function
-
- Options… Enable or disable tracepoints using the Sherlock options dialog.
-
-
- Dump Stats Prints statistics to the Sherlock window.
-
-
- Clear Stats Clears all statistics.
-
-
- Open File…/Close File Opens or closes the Sherlock log file. When the Sherlock log is
-
- open, all output to the Sherlock window is sent also to the log.
-
-
-
- Close Window/Open Window Opens or closes the Sherlock Window.
-
-
- User Dumps 1, 2 and 3 Calls the dumpCallBack routines.
-
-
-
- The Sherlock Options Dialog
-
- The Sherlock Options Dialog appears when you select the “Options” item from the Sherlock menu.
- This dialog contains a text box labeled “Sherlock arguments.” Enter the names of tracing
- statements to be enabled or disabled in this box. Precede the names of the tracing statements by
- ++ or -- to enable or disable them respectively. Use the wildcard characters * and ? to enable or
- disable groups of tracing statements. * stands for any string and ? stands for any character.
-
-
- For example, ++f enables the statement labeled f and --g disables the statement labeled g. ++f*
- enables all tracing statements whose name starts with f*. Finally, ++f* --fa* enables all tracing
- statements whose name starts with f except those tracing statements whose name starts with fa.
- The order of these specifications is significant: they are evaluated left to right.
-
-
- Check the box marked, Echo Sherlock output to a disk file…, to send Sherlock output both to the
- log window and to a disk file.
-